Skip to content

feat: surface quality/lifecycle commands in prime, template, and doctor#2664

Closed
seanmartinsmith wants to merge 2 commits intosteveyegge:mainfrom
seanmartinsmith:feat/prime-template-improvements
Closed

feat: surface quality/lifecycle commands in prime, template, and doctor#2664
seanmartinsmith wants to merge 2 commits intosteveyegge:mainfrom
seanmartinsmith:feat/prime-template-improvements

Conversation

@seanmartinsmith
Copy link
Contributor

@seanmartinsmith seanmartinsmith commented Mar 17, 2026 •
edited
Loading

Summary

Surfaces existing but undiscoverable commands in prime output (CLI mode) and
the beads-section.md template. Adds doctor --check=conventions as a composite
of existing checks (lint + stale + orphans). No new commands or behavior -
just visibility for what's already there.

MCP mode and beads-section-minimal.md are unchanged.

Context

#2611 and #2612 documented the discoverability gap from the command/flag
alias angle - agents trying intuitive names that don't match. #2639 and
#2638 address that by adding aliases so wrong guesses work.

this PR addresses the other side: agents that never try commands they don't
know exist. dogfooding on 100's of beads showed bd prime surfaces ~19 of 100+
commands. result: --acceptance never used, --validate unknown, bd human
reinvented manually, 26% of close reasons were terse one-liners.

this fix is adding bullet points to prime and the template - surfacing
features, not adding them. doctor --check=conventions wraps three existing
commands (bd lint, bd stale, bd orphans) into one pass, advisory only.

Changes

two commits, independently cherry-pickable:

  1. prime + template - adds Quality Tools, Lifecycle & Hygiene, Structured
    Workflows, and Close Reason Format sections to CLI prime output.
    beads-section.md gets a condensed version for non-hook agents.
  2. doctor --check=conventions - composite check using existing lint,
    stale (14-day threshold), and orphan detection. warns, never blocks.
    follows the existing doctorCheck pattern.

Test plan

  • bd prime --full shows new sections, bd prime --mcp unchanged
  • bd doctor --check=conventions runs without error (supports --json)
  • script test prime_content.txt, 3 unit tests for conventions check
  • beads-section-minimal.md unchanged

@seanmartinsmith
feat: surface quality, lifecycle, and workflow commands in prime and …
3c9be8d 
…template

Dogfooding on 85+ beads showed agents only see ~19 of 100+ commands via
bd prime. 26% of close reasons were terse one-liners, --acceptance was
never used, and --validate was unknown. This adds visibility for features
that already exist but were invisible to agents.

Prime output (CLI mode only) now includes:
- Close reason format template (Summary/Change/Files/Discovery)
- Quality tools section (--validate, --acceptance, --design, bd lint)
- Lifecycle & hygiene commands (defer, supersede, stale, orphans, etc.)
- Structured workflows (bd formula list, bd mol pour)

beads-section.md template (full profile) gets matching condensed sections
for non-hook agents (Codex, Factory, Mux, OpenCode).

MCP mode and beads-section-minimal.md are unchanged.
@seanmartinsmith
feat: add doctor --check=conventions for convention drift detection
1ff8e28 
Composite check that runs lint, stale, and orphan detection in one pass.
Advisory only - warns but never blocks, consistent with the "quality is
a choice" philosophy.

Three sub-checks:
- conventions.lint: open issues missing recommended template sections
- conventions.stale: issues inactive for 14+ days
- conventions.orphans: issues referenced in commits but still open

Each sub-check returns a doctorCheck following the existing pattern.
Supports both human-readable and --json output.
@seanmartinsmith seanmartinsmith mentioned this pull request Mar 17, 2026
Closed
4 tasks
@seanmartinsmith
Copy link
Contributor Author

seanmartinsmith commented Mar 17, 2026

related: #2654 fixes --validate to check the --acceptance field and adds validation.on-close config

@seanmartinsmith seanmartinsmith mentioned this pull request Mar 17, 2026
Open
@steveyegge
Copy link
Owner

steveyegge commented Mar 19, 2026

Most of this is good — surfacing existing commands in prime and the template is worthwhile, and doctor --check=conventions is a clean composition of existing checks.

However, the Close Reason Format section needs to come out:

## Close Reason Format
When closing non-trivial work, structure the reason:
Summary: [one line - what was done]
Change: [what changed and why]
Files: [key files modified]
Discovery: [what was learned that wasn't known at start]

This is a convention nobody follows yet — actual close reasons in our DB are mostly "Closed" or brief sentences. Injecting a prescriptive template into every agent's prime context burns tokens for a format with zero adoption. If we want structured close reasons, the path is:

  1. Discuss the convention as a team
  2. Use validation.on-close from your other PR (fix: --validate checks --acceptance field, add validation.on-close config #2654) to nudge toward it
  3. Only add it to prime once it's an established convention, not to bootstrap one

Please remove the Close Reason Format block from prime.go and the "Structure close reasons: Summary + Change + Files + Discovery" line from beads-section.md, then this is ready for another look.

steveyegge
steveyegge reviewed Mar 20, 2026
View reviewed changes
Copy link
Owner

@steveyegge steveyegge left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Crew Review: beads/crew/collins

Grade: B+ — Well-scoped PR that correctly surfaces existing features. One documentation bug, otherwise clean.

What This PR Does

Two commits:

  1. Prime + template — Adds Quality Tools, Lifecycle & Hygiene, Structured Workflows, and Close Reason Format sections to bd prime --full CLI output and beads-section.md.
  2. doctor --check=conventions — Composite advisory check wrapping existing bd lint, bd stale, and bd orphans into one pass.

Positive

  • Good scope discipline — surfaces features, does not add behavior. The conventions check is advisory-only (warns, never blocks).
  • Follows existing doctorCheck pattern correctly. Status values are statusOK/statusWarning only.
  • All dependencies verified to exist: findOrphanedIssues(), validation.LintIssue(), store.GetStaleIssues(), store.SearchIssues().
  • Script test (prime_content.txt) integrates with the existing scripttest framework.
  • beads-section-minimal.md is unchanged as claimed.
  • JSON output support on the conventions check.

Bug: Wrong flag name in prime output

The prime output says:

bd supersede <id> --by=<new-id>

The actual flag is --with, not --by (cmd/bd/duplicate.go:55):

supersedeCmd.Flags().StringVar(&supersededWith, "with", "", "Replacement issue ID (required)")

Should be:

bd supersede <id> --with=<new-id>

Minor Notes

  • Test coverage: The 3 unit tests only cover nil-store/no-git edge cases. No test exercises the happy path with actual issues. Acceptable since the sub-checks delegate to existing well-tested functions (LintIssue, GetStaleIssues, findOrphanedIssues).
  • The conventions check gracefully handles errors (non-git repos, missing store) — good defensive coding.

Verdict

Fix the --by to --with typo and this is ready to merge.

steveyegge added a commit that referenced this pull request Mar 21, 2026
@steveyegge @seanmartinsmith @claude
feat: surface quality/lifecycle commands in prime, template, and doct…
0fe9c03 
…or (fix-merge PR #2664)

Surfaces existing but undiscoverable commands in bd prime output (CLI mode)
and beads-section.md template. Adds doctor --check=conventions as a composite
of lint, stale, and orphan checks (advisory only).

Fix-merge changes:
- Remove Close Reason Format section (not an established convention yet)
- Fix --by to --with for bd supersede (matches actual flag name)

Co-Authored-By: seanmartinsmith <114885497+seanmartinsmith@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@steveyegge
Copy link
Owner

steveyegge commented Mar 21, 2026

Fix-merged to main as 0fe9c03. Applied two fixes:

  • Removed Close Reason Format section (per Steve's feedback — not an established convention yet)
  • Fixed --by to --with for bd supersede (per crew/collins review — matches actual flag name)

Thanks for the contribution! The core idea — surfacing undiscoverable commands — is solid.

@steveyegge steveyegge closed this Mar 21, 2026
julianknutsen pushed a commit to gascity/beads that referenced this pull request Mar 22, 2026
@steveyegge @seanmartinsmith
@claude @julianknutsen
feat: surface quality/lifecycle commands in prime, template, and doct…
7885f34 
…or (fix-merge PR steveyegge#2664)

Surfaces existing but undiscoverable commands in bd prime output (CLI mode)
and beads-section.md template. Adds doctor --check=conventions as a composite
of lint, stale, and orphan checks (advisory only).

Fix-merge changes:
- Remove Close Reason Format section (not an established convention yet)
- Fix --by to --with for bd supersede (matches actual flag name)

Co-Authored-By: seanmartinsmith <114885497+seanmartinsmith@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@steveyegge steveyegge steveyegge left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@seanmartinsmith @steveyegge